<?php

//============================================================================
//
// doc_classes.php
// ---------------
//
// Classes needed for s-audit documentation. The main docPage() class is in
// display_classes.php.
//
// R Fisher 01/11
//
//============================================================================

//----------------------------------------------------------------------------
// code Block

class codeBlock {

	// This class prints embedded code blocks for use in documentation. The
	// blocks present syntax coloured output if possible, plain if not. If
	// the plain text of the script/source file file exists, a link is given
	// which lets the browser receive it as plain text

	private $scr;		// The name of the code to include (like basename)
	private $scr_cp;	// path to the raw code
	private $scr_cl;	// link to raw code
	private $scr_hp;	// path to HTMLized code
	private $scr_hl;	// link to HTMLized code

	public function __construct($scr)
	{
		// Set variables so show_script() can find everything

		$this->scr = $scr;

		$this->scr_cp = CB_DIR . "/$scr";
		$this->scr_cl = CB_URL . "/$scr";
		$this->scr_hp = CB_DIR . "/${scr}.html";
		$this->scr_hl = CB_URL . "/${scr}.html";
	}

	public function show_script()
	{
		// Show the Vim syntax coloured script if we can. If not, fall back
		// to using the script

		$ret = "\n\n<div class=\"codeBlock\">\n"
		. "  <div class=\"codeBlockHead\">Source of $this->scr</div>";

		if (file_exists($this->scr_cp))
			$ret .= "  <div class=\"codeBlockLink\">(<a href=\""
			. "$this->scr_cl\">view as plain text/download</a>)</div>";

		$ret .= "\n<pre class=\"codeBlock\">";

		if (file_exists($this->scr_hp))
			$ret .= file_get_contents($this->scr_hp);
		elseif (file_exists($this->scr_cp))
			$ret .= file_get_contents($this->scr_cl);
		else
			$ret .= "Someone forgot the code!<br/>$this->scr_cp";

		return $ret . "\n  </pre>\n  </div>";
	}


}

//----------------------------------------------------------------------------
// docHelper

class docHelper {

	// This class provides shorthands for commonly used blocks of text in
	// the s-audit documentation

	private $cname;
		// the audit class name

	private $generic_key;
		// where we hold a copy of the generic_key

	protected $cols;

	function __construct($cname = false)
	{
		$this->cname = $cname;
		$this->cols = new Colours;

		// We're likely to want to include a key

		$class_key = KEY_DIR . "/" . preg_replace("/class/", "key",
		basename($_SERVER["PHP_SELF"]));

		if (file_exists($class_key)) {
			include_once($class_key);
			$this->grid_key = $grid_key;
		}

		// And we definitely want the generic key

		include(KEY_DIR . "/key_generic.php");

		$this->generic_key = $generic_key;
	}

	function colour_key($data)
	{
		// Print HTML which explains the colours used in fields on audit
		// grids. Called with an array of arrays of the form text, class,
		// style

		$ret = "\n<dd>\n<ul class=\"dockey\">";

		foreach($data as $arr) {

			// Omit "NOTE"s

			if (preg_match("/NOTE/", $arr[0]))
				continue;

			// We may be given a class or an inline style.  
			
			$il = (isset($arr[2]) && ($arr[2]))
				? "style=\"$arr[2]\""
				: "class=\"$arr[1]\"";

			// Some of the keys have line breaks in them, and we don't want
			// those

			$txt = str_replace("<br/>", " ", $arr[0]);
			$ret .= "\n  <li><div ${il}>$txt</div></li>";
		}

		return $ret . "\n</ul>\n</dd>";
	}

	function doc_class_start()
	{
	
		// All the class pages start in the same way, so use this function
		// instead of having the same HTML in every page. NOTE THAT IT OPENS
		// A DEFINITION LIST, BUT DOESN'T CLOSE IT! (doc_class_end() does
		// that.)

		echo "\n\n<h1>" . ucwords($this->cname) . " Page</h1>"
		. "\n\n<p>The information presented by this page is generated by"
		. "\n<tt>s-audit.sh</tt>'s <a href=\"" . DOC_URL . "/02_client/"
		. basename($_SERVER["PHP_SELF"]) . "\">$this->cname class</a>.</p>\n";

		?>

<p>Listed below are fields which can occur in a standard audit. Features or
software which are not offered by any of the hosts in the audit will be
omitted from the grid, so do not be concerned if you do not see all of the
fields listed on this page.</p>

<p>Many fields can have colour coding. Note that coloured borders and
coloured fields can be combined to draw the user's attention to more than
one thing.</p>

<p>Fields with &quot;(+)&qout; in their header were unexpected, and
dynamically added into the audit. If you see a lot of these fields, you may
need to update your interface software.</p>

<dl>
	<dt>hostname</dt>
	<dd>The hostname of the server or zone. Global zones, which may be
	physical servers, logical domains, or virtualized environments, are
	displayed in left-aligned, <strong>bold</strong> face. Non-global zones
	are indented, and shown in a lighter face.</dd>

	<dd>Rows have a background colour dictated by the type of environment.
	They are as follows:</dd>

	<?php
		echo $this->colour_key($this->generic_key["hostname"]);
	}

	function doc_class_end() {

		// Close off the class documentation by explaining the "audit
		// completed" field
	?>

<dt>audit completed</dt>
<dd>Shows the time the audit was performed. Audits more than 24 hours old
are highlighted by amber field, those older than a week by a red
field.</dd>

<dd>Audits which, according to the clock on the host running the interface,
were performed in the future, or audits performed before the time defined in
<tt>LOWEST_T</tt> in <tt>_conf/site_config.php</tt> are highlighted by an
orange field. This is intended to help the user spot machines with wildly
innacurate clocks.</dd>

	<?php
		echo $this->colour_key($this->generic_key["audit completed"]),
		"\n\n</dl>";
	}

	public function file_on_sys($name, $def)
	{
		echo "<p>On this system";

		if (defined($def)) {
			$path = constant($def);
			echo " the $name file ";

			echo (file_exists($path))
				? "can be found at <tt>$path</tt>"
				: "is expected to be at <tt>$path</tt>, but does not exist";
		}
		else {
			echo ", no path is set for the $name file. Please define
			<tt>$def</tt> in the configuration files";
		}

		echo ".</p>";
	}

	public function list_omitted($index, $class = "omitlist")
	{
		// We don't have an omitted data file any more.

		return;
	}

}

?>
